Release 10.1A: OpenEdge Development:
Web Services

Building and deploying Progress 4GL Web services

A typical order of tasks to bring a Progress 4GL Web service from conception to implementation include:

Defining client requirements
Preparing the AppServer application
Defining the Web service
Configuring a WSA instance
Deploying the Web service
Writing a client and testing the Web service
Providing the Web service to users
Tuning the Web service and its WSA instance

The following sections provide more information on these tasks.

Defining client requirements

The first step in building any new Web service application is to understand the requirements of its intended clients. This can help with deciding certain details of a Web service design and implementation, including (but not limited to):

The session model to support with a new Web service application. For more information, see OpenEdge Application Server: Developing AppServer Applications
The types of Open Client objects to use in designing the Web service (also closely associated with the session model of the Web service). For more information, see OpenEdge Development: Open Client Introduction and Programming .
The SOAP formats (style and use) to support for Web service deployment. For more information, see Chapter 2 "WSDL and Web Service Objects in Progress 4GL Web Services" and Chapter 4, " General Client Programming Model for Progress 4GL Web Services."
Note: For an existing AppServer application, the requirements of intended Web service clients are already likely to be known and reflected in the existing AppServer application.

Preparing the AppServer application

Once the client requirements are known, you can design and write a new AppServer application for a Web service, or decide whether to enable an existing AppServer application as a Web service. You can enable the complete interface to a smaller application, or selected interface components of a larger application, as client requirements dictate. The session model that the AppServer must support for a new application also determines the complexity of its programming. For information on configuring and programming AppServers, see OpenEdge Application Server: Administration and OpenEdge Application Server: Developing AppServer Applications .

Defining the Web service

After you have built and compiled the Progress r-code for the AppServer application, you can use ProxyGen to prepare the application for deployment as a Web service. As you define the Web service, your knowledge of the application and client requirements helps to decide how best to organize and include the procedures of your application as Open Client objects and methods. For information on how to use ProxyGen to define the Web service, see OpenEdge Development: Open Client Introduction and Programming . ProxyGen saves the Web service definition as a WSM file.

Configuring a WSA instance

At any time in the cycle of Web service design and development, you can create and configure a WSA instance to host your Web service when you are ready to deploy it. Many considerations might determine when and how you do this, such as the available server and network resources, as well as any other requirements that you determine for deploying the Web service (for example, support for different client SOAP formats). You also need to think carefully about security requirements for the WSA instance and the Web services you plan to deploy to it.

Note: Creating and configuring a WSA instance is a two-step process in which you (1) use the Progress Explorer to define and Progress Explorer or the wsaman utility to configure the instance on the OpenEdge side, and (2) use whatever tools are available to define the WSA instance as a Java servlet to your JSE. After completing the creation and configuration of a WSA instance, you might have to restart the JSE to start up the Java servlet for that instance to deploy Web services to the context of the WSA instance. See your JSE documentation for information on the requirements for running and accessing instances of the JSE context.

For information on how to create and configure WSA instances, see OpenEdge Application Server: Administration .

Deploying the Web service

After you have defined the Web service and configured a WSA instance for it, you can deploy the Web service definition to that WSA instance using Progress Explorer or the wsaman utility.

Caution: You can update a deployed Web service to change its deployment information and object definitions. However, never update a deployed Web service that you have enabled for live access by production clients. Instead, create a new version of the Web service with the intended updates and deprecate the old version of the Web service once all clients have moved to the new version.

You can also adjust the values for a variety of properties of a deployed Web service or change the default values that are automatically assigned when you first deploy a Web service.

For more information on deploying and managing a deployed Web service, see OpenEdge Application Server: Administration .

Writing a client and testing the Web service

Typically, the earliest that you can begin writing the code to access a Web service in a client application is after you have obtained the WSDL file for a Web service (and any required documentation). You can obtain this WSDL file before deployment by selecting the option to generate it directly from ProxyGen when you first define the Web service.

However, the order in which you actually develop the client and Web service side of a complete application solution depends on your application and the environment in which it runs. For example, if you are writing both the client and Web service as a single application solution for an intranet environment, you might begin developing the client side as a way of determining the exact requirements for the Web services you need to develop.

There are also additional techniques for testing and debugging a Web service with or without writing a client for it.

Caution: Before you begin testing a Web service, deploy it to a WSA instance that is dedicated for Web service testing and otherwise isolated from the intended client domain. This allows you to enable the Web service for access by clients doing preproduction testing without making it visible and “live” to post-production clients. Once testing is complete, you can redeploy or import the Web service to the context of the production WSA instance.

For more information on writing client applications for a 4GL Web service, see Part II, "Clients Accessing Progress 4GL Web Services." For more information on testing and debugging Web services, see Chapter 7, " Testing and Debugging Progress 4GL Web Services."

Providing the Web service to users

When you initially deploy a Web service, it is disabled from access by clients over the network. This allows you to adjust Web service property values and perform other administrative tasks, such as setting up the WSA instance to distribute the WSDL file to users, before making it visible and accessible to the intended network clients. When the Web service is ready for production, you can enable it for client access using an option in Progress Explorer or the wsaman utility.

Caution: Do not make a newly deployed Web service available to production clients until you ensure that all Web service testing, updating, and administration is complete to support that Web service in the production client domain. (See the "Writing a client and testing the Web service" section.)

For more information on when and how to enable and disable Web services for client access, see OpenEdge Application Server: Administration .

Tuning the Web service and its WSA instance

Both during preproduction testing and full production access by real clients, you can monitor various run-time statistics accumulated for both the WSA instance and the Web services that are deployed to it. Over time, this will allow you to adjust WSA instance and Web service property values to yield the best performance metrics.

Note: Remember also to monitor and tune the AppServer configurations that support your Web services along with monitoring and tuning the Web services themselves.

For information on monitoring and tuning AppServer configurations, WSA instances, the Web services that are deployed to WSA instances, see OpenEdge Application Server: Administration .